/*
 *                 Sun Public License Notice
 * 
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 * 
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
 * Microsystems, Inc. All Rights Reserved.
 */
/*
 * ActionFactory.java
 *
 * Created on February 14, 2005, 11:35 PM
 */

package actions;

import javax.swing.*;

/**
 * If the <code>instance</code> argument to an <code>ActionManager</code>'s constructor implements this interface, then
 * <code>create()</code> will be called to construct those actions which do not specify a <code>method</code> argument
 * in the actions XML file the <code>ActionManager</code> reads.
 * <p>
 * For most applications, it is not necessary to implement this interface.  Use
 * it if either you have legacy actions and want to adapt them to work within
 * the actions framework, or if you need to supply custom components for certain
 * items in menus, toolbars, etc.
 *
 *
 * @author Tim Boudreau
 * @see ActionManager
 */
public interface ActionFactory {
    static final int MENU = 0;
    static final int POPUP = 1;
    static final int TOOLBAR = 2;
    static final int SUBMENU = 3;
    static final int SEPARATOR = 4;

    /**
     * Create an action for the given id.  If null is returned, the standard
     * reflection-based method of invoking actions is used.  If null is 
     * returned, either a method with the named.
     *
     * @param id The ID of an action.
     * @return A custom action
     */
    public Action create (String id);

    /**
     * Creates a custom component for a given ID and action.  This method 
     * allows the implementor to supply a custom component for a given
     * menu/toolbar/menu item/toolbar button, etc.
     * @param id An ID of the component or container in question
     * @param action the Action instance, if any, associated with the 
     *        id
     * @param context the type of context for which a component is being
     *  requested - can be <code>MENU, TOOLBAR,</code> or <code>SUBMENU</code>
     */
    public JComponent createComponent (String id, Action action, int context);
}
